<html>
<head>
	<meta http-equiv="Content-Type"	content="text/html; charset=iso-8859-1">
	<meta name="GENERATOR" content="The DarkSite">
	<title>Readme for Haiku Unified Matrox graphics driver</title>
</head>
<body>
<h2 align="center">Unified Matrox graphics driver for Haiku</h2></align><br><br>
<hr>
<h3><strong>NOTE PLEASE:</strong><br>
You use this software at your own risk! Although I don't expect it to damage your PC, videocard or Monitor, I cannot guarantee this!</h3>
<hr>
<h2>Supported cards:</h2>
<ul>
	<li>Millenium I (preliminary)
	<li>Millenium II (preliminary)
	<li>G100
	<li>G200
	<li>G400
	<li>G450
	<li>G550 (including the PCIe x1 version)
</ul>
<br>
<hr>
<h2>Features:</h2>
<ul>
	<li>Millenium I/II (preliminary):
	<ul>
		<li>Hardware cursor support;
		<li>Full 2D acceleration;
		<li>Full BWindowScreen support (used for hardware pageflipping, scrolling/panning and acceleration in applications/games);
		<li>Sync_on_green support;
		<li>DPMS support;
	</ul>
	<li>G100-G550:
	<ul>
 		<li>Hardware cursor support on one head;
		<li>Full 2D acceleration;
		<li>Full BWindowScreen support (used for hardware pageflipping, scrolling/panning and acceleration in applications/games);
		<li>Full card coldstart support (important if you use such a card as secondary videocard);
		<li>Sync_on_green support: G400, G450 and G550 apparantly miss the needed board wiring to actually support this fully though;
		<li>DPMS support on all heads;
	</ul>
	<li>G200-G550:
	<ul>
		<li>B_YCbCr422 hardware overlay support on one head (including 'hardware zoom');
		<li>MMS (multiple heads using multiple GPUs) cards are supported on all heads (confirmed a G200MMS working OK), although you can't use the non-primary heads without a video consumer node or other special software;
	</ul>
	<li>G400-G550:
	<ul>
 		<li>Dualhead functionality;<br>
		<li>TVout support: Desktop modes: G400 only for now; Video modes: G400-G550.<br>
	</ul>
    <strong>Note:</strong> You need <strong>Dualhead Setup 0.04</strong> (BeBits) for use of Dualhead and/or TVout modes.
</ul>
<strong>current MGA driver limitations:</strong><br><br>
<ul>
	<li>If you want BScreen 'Sync_to_Retrace' capability make sure you enabled 'assign IRQ to VGA card' in your system BIOS (if available);
	<li>Expansion RAM modules are not supported as far as I know;
	<li>G400 cards have overscanning rubbish visible on the top of the screen if spaces with virtual height are used on the secondary head in monitor mode. This cannot be fixed decently, and is caused by a MAVEN hardware design fault;
	<li>DVI output is not yet supported.
</ul>
<br>
<hr>
<h2>Installation:</h2>
If you encounter bugs, please checkout the driver's <a href="http://web.inter.nl.net/users/be-hold/BeOS/MGAdriver/index.html">website</a> to see if it's already on the todo list. You can also checkout the <a href="UPDATE.html">UPDATE</a> file included with this driver to see if it should have been fixed. If you think it's prudent, or if you are unsure, then please fill out the <a href="http://web.inter.nl.net/users/be-hold/BeOS/MGAdriver/bugreport.html">bugreport</a> on the site or send me an <a href="mailto:info.be-hold@inter.nl.net">Email</a>. Make sure you are as precise as possible because that will make things easier to trackdown and fix...<br>
<br>
<br>
OK, now that's all said let's get to it ;-)<br>
<br>
In contrary to what I have said before you don't need to de-install official Be drivers for this driver to work correctly. This driver will install in the user part of the BeOS, so not in the system part where the official drivers are.<br>
BeOS first checks (during boot) if there are 'user-addons' that should be loaded for a device. If not, it loads it's own drivers (if any). You can select which driver should be loaded by hitting the spacebar as soon as the BeOS 'icons' screen appears. If you select <strong>disable user addons</strong> the system will load it's own drivers. If you don't do anything, the system will load the Haiku Matrox graphics driver.<br>
<br>
Since BeOS only supports all Matrox cards upto and including G400 you will end up in VGA grayscale videomode if you have a G450 or G550. Otherwise, you will have a normal colorfull Desktop. Only BeOS will be using it's own official drivers in this case...<br>
<strong>Note:</strong> This might turn out to be handy if you run into trouble upon testing the driver, or if you are 'tweaking' the mga.settings file...<br>
<br>
<br><br>
<strong>actual INSTALLATION, part 1:</strong><br>
<br>
If you used Mark Watson's G400 driver (upto and including V0.12), or the (open)BeOS driver V0.13 alpha1 
 (which was based on Mark's driver directly), you need to do an extra manual step *once* in order to activate the new driver:<br>
<br>
You must <strong>remove Mark's driver manually</strong>. (If you don't, the new driver won't be loaded!)<br> 
In order to do this, you need to delete two files (and reboot afterwards). Here's how:<br>
<ul>
	<li>In: <strong>home/config/add-ons/accelerants/</strong><br> 
		delete: <strong>MGAGX00.accelerant</strong> 
		(You *should* find 'mga.accelerant' there if you already installed the Haiku driver V0.13 alpha2 or up.)
	<li>In: <strong>home/config/add-ons/kernel/drivers/bin/</strong><br>
		delete: <strong>gx00.driver</strong> 
		(You *should* find 'mga.driver' there if you already installed the Haiku driver V0.13 alpha2 or up.)
	<li>You can also delete the <strong>mgaGx00.log</strong> logfile which is generated by Mark's driver in your <strong>home</strong> folder. (The logfile called 'mga.(/dev/graphics name).0.log' the new driver generates is located there also. You may delete that if it gets too big: the Haiku driver simply creates a new one from scratch when needed. The same applies for a possibly existing 'mga.(/dev/graphics name).1.log' file, generated by clone accelerants.)
</ul>
If you install a new version of the Haiku MGA driver later on you won't encounter this manual thing again: it's a one-time thing only.<br>
<hr>
<strong>Note: If you used the (non-released) 3D capable Matrox driver please remove it, as it may interfere with the Haiku driver.</strong>
<hr>
<br>
<br>
<strong>actual INSTALLATION, part 2:</strong><br>
<br>
Doubleclick on the install.sh file and follow the instructions. You have to reboot in order to load the driver. Make sure you read the <strong>Settings</strong> information below before you do that...<br>
<br>
<br>
<strong>alternate INSTALLATION (part 2) method:</strong><br>
<br>
Unzip the zip file that contains the driver to the root folder. Now reboot and you should be using the new driver.<br>
<br>
<br>
<strong>DE-INSTALLATION:</strong><br>
<br>
Currently there's no uninstall script included. Just do it manually:<br>
<br>
Delete the <strong>mga.accelerant</strong> file in <strong>home/config/add-ons/accelerants/</strong><br>
Delete the <strong>mga.driver</strong> file in <strong>home/config/add-ons/kernel/drivers/bin/</strong><br>
Delete the <strong>mga.settings</strong> file in <strong>home/config/settings/kernel/drivers/</strong><br>
Delete the <strong>mga.driver shortcut</strong> in <strong>home/config/add-ons/kernel/drivers/dev/graphics/</strong> which pointed to the file <strong>mga.driver</strong>.<br>
<br>
You have to reboot in order to apply the original configuration.<br>
<br>
<br>
<hr>
<a name="settings"></a><h2>Settings:</h2><br>
Please read this information carefully *before* installing and using the Haiku Matrox MGA driver. It might spare you some trouble afterwards..<br>
<p>The driver uses a file named <strong>mga.settings</strong> to determine how to use your card. After installation this file will be located at <strong>home/config/settings/kernel/drivers/</strong>. How you should setup this file depends on what you want to do with the driver. While it has a 'failsave' default configuration, you might be able to do better than that... Anyway, read the nifty details below.<br>
<br>
<strong>Note:</strong> The driver only reads this file during it's initialisation. This means that you have to reboot in order to let changes take effect.<br>
<br>
<br>
<br>
<strong>mga.settings driver configuration:</strong><br>
<ul>
	<li><strong>usebios:</strong><br>
The name of this item may be somewhat misleading, it might be changed in the future. It actually tells the driver if it should coldstart the card or not. The driver will rely on the VGA BIOS to have coldstarted the card before BeOS booted if you specify 'true'.<br>
To make things look even more complex the driver actually uses the BIOS to determine your cards specifications on *both* possible settings.
	<ul>
		<li><strong>false:</strong> (default setting in V0.13 beta2 and up)<br>
		If you specify <strong>usebios false</strong> the driver will coldstart the card, which is the preferred way of doing it because of the better tuned setup if all is right. If you encounter trouble with this setting then please inform me, because it should be working reliably on all Gxxx cards! This setting also enables you to use your Matrox card as a secondary card in your system. Be advised though that BeOS officially does not (yet) support multiple VGA cards, so you need special software in order to be able to actually use it (a video consumer node for instance).
		<li><strong>true:</strong> (default setting in V0.13 beta1)<br>
		If you have a G450 or G550 and you are using the old V0.13 beta1 (or an even older) driver, specify <strong>usebios true</strong> (If you don't your screen will probably go dark when you restart BeOS). If you have trouble on other cards (or while using the latest driver) use this setting also. If this setting gives you trouble, then (also) please let me know.
	</ul>
	<strong>Notes:</strong>
 	<ul>
 		<li>On V0.13alpha2 and before usebios had no effect on G400 cards. These cards were always coldstarted.
		<li>Millenium I and II cards do not (yet) have coldstart support. The usebios setting has no effect here.
 	</ul> 
	<li><strong>memory:</strong> (disabled by default)<br>
		This option enables you to override the 'memory amount autodetection' of the driver. While you did need it on all driverversions for most cards upto now, you don't need it anymore starting with V0.13beta1. There is only *one* exception: If the V0.13beta1 (and up) driver reports not being able to process the Pins BIOS info, it will default to a failsafe RAM amount. This might be too low a value, so you might want to tune that then. Specify the RAM amount in Mb (use only 'whole' numbers!).<br>
This option is disabled by default (preceded by a '#').<br>
	<strong>Note:</strong>
	<ul>
		<li>Memory detection does not work (yet) on Millenium I and II cards. Millenium I is preset to having 2Mb RAM, while Millenium II is preset to having 4Mb RAM. If you have more and want to use it, use the <strong>memory</strong> option to set the driver to the correct amount of RAM.
	</ul>
<li><strong>hardcursor:</strong><br>
	The hardcursor capabilities of the MGA cards are limited to one head only (except for MMS cards). A hardcursor is nessesary though for DirectWindow windowed mode support.
	<ul>
		<li><strong>false:</strong> (default setting in V0.13 beta2 and V0.14)<br>
		If you want to use dualhead and also want a visible cursor on both heads, select <strong>hardcursor false</strong>. This setting is used by default these days because it's a 'failsafe' setting that works independently of the selected videomode.
		<li><strong>true:</strong> (default setting in V0.13 beta1 and V0.15 and later)<br>
		A software cursor 'flickers' a bit sometimes because it has to be redrawn constantly. So for use in singlehead mode <strong>hardcursor true</strong> is the preferred setting. For DirectWindow windowed mode functionality you need to use this setting also (Chart demo app for instance).
	</ul>
	<strong>Notes:</strong>
 	<ul>
 		<li>Starting with V0.13beta1 the hardcursor also works on G100 cards.
 		<li>Driverversion V0.14 also introduces Millenium I and II hardcursor support.
	</ul>
<li><strong>logmask:</strong> (set to disabled by default)<br>
The logmask option is very handy to track down trouble in the driver. You should only enable this if you are doing so, otherwise keep it turned off because it slows down your system. (All lines have a '#' preceding 'logmask' by default.) Logging creates a logfile called <strong>mga.(/dev/graphics name).0.log</strong> in your <strong>~ (home)</strong> folder. A second logfile may get created depending on how the driver is used (on cloning; for BWindowScreen for example). The second file is called <strong>mga.(/dev/graphics name).1.log</strong>, and it will also be in your home folder.<br>
<strong>Note:</strong>
<ul>
<li>You may only enable *one* logmask-line. The value you place after it (hexadecimal 32bit) determines what will be logged. The first 7 digits determine the part of the driver that will be logging, the last single digit determines the level of logging (like 'all messages', or only 'error messages').
</ul>
<li><strong>dumprom:</strong><br>
Dumprom is another 'tool' for bug-tracking purposes.
	<ul>
		<li><strong>false:</strong> (default setting)<br>
		Keep it set to <strong>dumprom false</strong>, unless you want the driver to dump the contents of your VGA BIOS ROM in a file.
		<li><strong>true:</strong><br>
		<strong>dumprom true</strong> lets the driver dump a copy of your VGA BIOS in a file called <strong>mga.(/dev/graphics name).rom</strong> in your <strong>~ (home)</strong> folder.
	</ul>
<li><strong>greensync:</strong> (V0.14 and up)<br>
Greensync is used to enable an alternate monitor signal synchronisation setup used for some specific monitors outthere.
	<ul>
		<li><strong>false:</strong> (default setting)<br>
		Normal synchronisation signals are output only. Changes are, you will use this setting.
		<li><strong>true:</strong><br>
		<strong>greensync true</strong> lets the driver output 'Sync on Green' timing signals to the monitor also. On dualhead cards the secondary head remains outputting standard signals only: sync on green is not supported there. Don't use this option unless your monitor needs it. Otherwise you will probably get a distorted Desktop that's also too bright..
	</ul>
	<strong>Note:</strong>
<ul>
<li>Enabling sync on green does two things. It enables output of composite sync on the Hsync line (while keeping Vsync only on the Vsync line), and it adds this composite sync to the green signal output to your monitor. While outputting composite sync works on all cards, adding this to the green signal output only works on older cards, upto and including G200.
</ul>
<li><strong>primary:</strong> (set to disabled by default)<br>
Primary lets you force a certain card to be used as primary card in your system if you have multiple graphics cards installed: so it will display your desktop. To enable this (hack) feature uncomment this item and fill in the exact name of the card that is to be primary (as exported by the kerneldriver in /dev/graphics/). If you are going to select a card other than the one displaying your system's POST messages at bootup, make sure you also keep the default 'usebios false' setting as otherwise the card(s) aren't coldstarted by the driver.<br>
<strong>Note please:</strong>
<ul>
<li>Coldstarting doesn't work on Millenium I and Millenium II cards yet;
<li>Primary forces the primary card by preceding the exported name by a minus-sign (-) for the selected device. This ensures that this device will be listed at the top in the /dev/graphics/ folder, which is alphabetically ordered. Please make sure you enable the 'primary' feature on just one graphics driver, otherwise it's effect isn't 'guaranteed'.
</ul>
</ul>
<br>
<strong>Notes:</strong>
<ul>
 <li>If you want to use TVout or Dualhead modes, you need <strong>Dualhead Setup V0.04 or later</strong>. You can download this <a href="http://www.bebits.com/app/1401" target="blank">application</a> from BeBits.
</ul>
<hr>
<br>
<a href="mailto:info.be-hold@inter.nl.net">Rudolf Cornelissen.</a>
<p>(Page last updated on May 13, 2006)</p>
</body>
</html>
